🔎 Previews:

• https://clerk.com/docs/pr/dsfeat-custom-flow-apis/nextjs/reference/hooks/use-sign-in
• https://clerk.com/docs/pr/dsfeat-custom-flow-apis/nextjs/reference/hooks/use-sign-up
• https://clerk.com/docs/pr/dsfeat-custom-flow-apis/nextjs/reference/hooks/legacy/use-sign-in
• https://clerk.com/docs/pr/dsfeat-custom-flow-apis/nextjs/reference/hooks/legacy/use-sign-up
• https://clerk.com/docs/pr/dsfeat-custom-flow-apis/guides/development/custom-flows/authentication/email-password
• https://clerk.com/docs/pr/dsfeat-custom-flow-apis/guides/development/custom-flows/authentication/email-password-mfa
• https://clerk.com/docs/pr/dsfeat-custom-flow-apis/guides/development/custom-flows/authentication/email-sms-otp
• https://clerk.com/docs/pr/dsfeat-custom-flow-apis/guides/development/custom-flows/authentication/legacy/email-password
• https://clerk.com/docs/pr/dsfeat-custom-flow-apis/reference/javascript/sign-in-future
• https://clerk.com/docs/pr/dsfeat-custom-flow-apis/reference/javascript/sign-up-future
• https://clerk.com/docs/pr/dsfeat-custom-flow-apis/reference/javascript/types/errors

What does this solve?

This PR adds documentation for our new custom flows APIs, which are available in JavaScript-based SDKs built on top of React. These APIs will become the default APIs in the next major version of @clerk/react.

What changed?

One of the challenges of documenting these new APIs is that they've diverged from the APIs previously used for other SDKs, primarily our iOS and Android SDKs. This poses a unique challenge because the concept of what must be done to accomplish a sign-in or sign-up is now dependent upon the SDK used, whereas the current documentation depends on all SDKs using the same foundational ideas. For example, the new APIs no longer have the concept of "preparing", which the current docs reference. To alleviate this, the new guides utilize the <If> conditional component to selectively render different language and code examples based on the selected SDK, which allows us to directly reference the new API methods when the currently selected SDK is one that utilizes the new APIs.

This, however, causes another issue, which is what content should be shown when the current selected SDK doesn't have any examples for custom flows? As is, selecting a SDK such as Express would result in neither of the <If> statements being true, which would prevent any content from showing. To prevent showing blank content, the new guides utilize the sdk front matter attribute to only show the guides in the sidebar when a relevant SDK is selected.

Also, since the previous APIs are still available for backwards compatibility, the original docs have been copied to the /legacy folder to allow customers to still access the guides for reference.

Note

As of writing, the legacy guides do not utilize the sdk front matter attribute, but they probably should, otherwise the sidebar will look like this:

The new custom flow APIs are built upon the SignInFuture and SignUpFuture classes. The documentation for these new classes have been added alongside the existing SignIn and SignUp API documentation, and serves as the canonical reference documentation for the signIn and signUp exports of the new useSignIn and useSignUp hooks.

Checklist

• I have clicked on "Files changed" and performed a thorough self-review
• All existing checks pass